Icon Archiver documentation   Version 2.2 June 1997 ©1996-97 Alessandro Levi Montalcini Technical support, permissions, suggestions: C.so Re Umberto 10 mailto:alm@kagi.com 10121 Torino mailto:alm@torino.alpcom.it Italy Online shareware registration: Software download and information: http://order.kagi.com/?67 http://persoweb.francenet.fr/~alm ftp://ftp.alpcom.it/software/mac/LMontalcini • Shareware: $25 ◊ This program is distributed as shareware and costs $25. If you use it, please save a copy of the Register utility with the button below and launch it. Enter your name, your email address (if available), and the number of licenses you wish to purchase. Save, copy or print the data from the Register application and send it to Kagi along with your payment. Kagi will process your registration and forward your payment to me. If you’re on the Internet, an online registration site is also available at the above URL. ◊ Your personal registration code for the Icon Archiver will be sent back to you as quickly as possible when you register. Entering the code disables the registration request and removes the “unregistered” message from the Sticker window. If you have no email address you should select the postcard receipt option in the Register application, so that Kagi can send you back your registration code. Kagi transmits the registration codes via email and paid postcard receipt only. ◊ If you don’t want to pay through Kagi, you can send your payment in cash directly to my Italian address. Please provide your name, your address, your email, and the name and version of the software you’re registering. ◊ You may want to get a copy of the complete ALM Share and ALM Free packages, which contain most of my shareware and freeware programs and can be registered at a very low price. The packages are available as two large compressed archives and can be downloaded from my web and ftp sites. ◊ Please register: your support is the only way for me to keep working on cool shareware programs. • Kagi registrations ◊ Payments sent via email and through the online registration site are processed within 3 to 4 days. You will receive an email acknowledgement when your registration is done. Payments sent via fax take up to 10 days. You will also be notified by email if you provide a correct internet email address. Payments sent via postal mail take time to reach Kagi and then up to 10 days for processing. Again, if you include a correct email address, you will hear from Kagi when the form is processed. ◊ If you pay with a credit card or First Virtual, you can email or fax the data to Kagi. Their email address is and their fax number is +1-510-652-6589. You can either copy the data from Register and paste it into the body of an email message, or you can save the data to a file and attach the file to an email message. There is no need to compress the data file, it’s already pretty small. If you have a fax modem, just print the data to the Kagi fax number. ◊ You can also pay with a wide variety of cash from different countries, or with a check drawn in US Dollars. Kagi cannot accept checks in other currencies. In both cases you should print the data using the Register application and send it to the address shown on the form, which is: Kagi 1442-A Walnut Street #392-67 Berkeley, California 94709-1405 U.S.A. ◊ If you have a purchasing department, you can enter all the data into the Register program and then select Invoice as your payment method. Print three copies of the form and send it to your accounts payable people. You may want to highlight the line that reminds them to include a copy of the form with their payment. ◊ Kagi cannot invoice your company. If you need an invoice, you must act on my behalf and generate the invoice and handle all the paperwork on your end. ◊ Please do not fax or email payment forms that indicate cash, check or invoice as the payment method. As far as we know, there is still no technology to transfer physical objects via fax or email and without the payment, the form cannot be processed. • Introduction ◊ The Icon Archiver is an extremely powerful database specifically designed for easy icon storage and retrieval. It can quickly scan whole disks or folders and grab all the icons they contain, including those you won’t ever see in the Finder and all icon archives created by other icon utilities. It can easily export them in most graphics formats, including the ones you need for your web pages. Drag & Drop is fully supported, so you can create or stick custom icons by simply dragging them around. All icons are compressed on the fly to save memory and disk space, and archives can contain a very large number of icons (unlike all other icon utilities which are limited to a few hundreds). Advanced features include removing duplicate icons, sorting them by shape, filtering them by size or color depth, and viewing them in many different ways. The Archiver includes native PowerPC code and its icon handling routines are highly optimized for maximum speed. ◊ Even if you hate custom icons, you’ll be fascinated by the number of icons that come out of a typical shareware CD-ROM like the ones that are bundled with many Mac magazines. No matter what you use your Mac for, this is guaranteed to give you countless hours of fun and entertainment as well as a much nicer desktop. • Cool features ◊ Icon archives created with the Icon Archiver can contain a very large number of icons (limited only by available memory); I have successfully created archives with more than 100,000 icons without any serious slowdowns. By comparison, resource-based icon files such as those created by ResEdit, IconMania or Icon Collector are limited to less than about 500 icons (there can be no more than 2,727 resources in one file and performance is seriously affected long before that limit is reached). ◊ Opening and saving icon archives is extremely fast since it requires only one large data transfer. This is the optimal way to access slow devices such as CD-ROM drives, which makes the Archiver your tool of choice for creating and distributing your own icon collections. ◊ Icons are stored in a compressed format both in RAM and on disk; typical savings are about 50% of the actual icon size, but the figures are a lot higher for black & white icons and even higher if the disk’s minimum allocation block size is taken into account. An icon archive can be further compressed by about 50% with compression utilities such as StuffIt, Compact Pro or DiskDoubler. Compressing custom icons directly with one of these compression utilities is not nearly as efficient, since the compression and decompression processes are a lot slower and the final compressed archive is not much smaller than a plain Icon Archiver archive. ◊ Icons can easily be exported back to the most useful icon and graphics formats, such as custom icons , PICT, PNG, cicn, text, and even C source code; the GIF, JPEG and TIFF formats are directly supported on PowerPC machines through Yves Piguet’s freeware clip2gif utility. You can quickly export and convert any number of icons with one easy step, so anyone working with html should definitely try out the Archiver. ◊ Macintosh Drag & Drop is fully supported; you can drag files, folders or disks to an Archiver window to grab all the icons they contain, and you can create custom icon files by dragging one or more icons from an Archiver window to a Finder window. Dragging to the Finder trash and between Archiver windows is also supported. All these features obviously require the Drag Manager (optional in System 7.1, always available in System 7.5 and later); if the Drag Manager is not available, the same operations can be achieved by using traditional methods such as drag&drop over the application’s icon, copy and paste, and the “export” menu item. ◊ The Sticker window can be used to paste custom icons directly onto any Finder item by simply dragging a file, folder or disk into the Sticker window (this requires the Finder to be scriptable). Holding down the command key inverts the process and copies the item’s icon (including non-resource icons such as disk icons) to the sticker window. No other icon utility lets you add a custom icon to an existing item without opening the Get Info window and without even quitting the Finder. ◊ The Archiver uses undocumented Layer Manager calls (when available) to make its windows behave like the Finder’s windows: icons can be dragged from an Archiver window to the Finder or into another application without bringing the Archiver to front. This means you can create or stick custom icons without ever leaving the Finder. ◊ The Archiver converts all icon formats to System 7’s icon family format; this makes it easy to grab 'cicn', 'ICON' and 'SICN' resources, which usually require a lot of manual work before they can be used as custom icons. By the way, since the Archiver grabs all icon resources in any kind of file, it can easily read icon files created by other utilities such as ResEdit, IconMania or Icon Collector (note that the opposite is not true because the Archiver stores icons in the data fork and uses a special compressed format). Icons found by the Archiver can be dragged to the Finder or to any other drag-aware application, as well as saved in an archive or exported as custom icons. Pictures can also be dragged or pasted into the Archiver, which makes it easy to build those cool multi-icon Finder images. ◊ The Icon Archiver code is highly optimized and runs native on Power Macs. List scrolling, icon sorting and duplicate icons removal are a lot faster than with any other icon-oriented application (as a matter of fact, I believe that duplicate icons removal is not even available in any other application). As an example, sorting 100,000 icons takes less than 10 seconds on a Power Mac 6100/60, and removing duplicates doesn’t take much longer. ◊ All time-consuming operations such as scanning a whole CD-ROM or exporting hundreds of icons can be performed in the background while you keep using your Mac for other tasks. Note that when the Icon Archiver is in the background, the numbers in the progress window are updated more frequently; this gives away more CPU time to the foreground process. The Archiver’s icon scanning or exporting, however, is not running any faster so you may want to leave the Archiver in the foreground if you’re not using your Mac for anything else during the scan. ◊ Last but least, the Archiver is better than the Finder for managing icon collections because you’re not allowed to store many custom icons in one Macintosh folder (when you open a folder with more than a few hundred items in it, the scrollbars can’t be used any longer because the window area is too large for them, and opening the window becomes extremely slow). This is not a serious limitation, since you can store the icons in separate folders, but it makes it hard to find duplicate icons. The Archiver, of course, doesn’t have this problem (or I wouldn’t be telling you about it, would I?). Besides, the Archiver automatically creates multiple destination folders if you ask it to export more than 200 icons. • Instructions ◊ Drag icons to and from Icon Archiver and Finder windows to export icons or scan files, folders and disks. Drag icons to drawing programs, text editors or scrapbook managers to export an icon’s image or name. Drag pictures or picture clipping files to an Archiver window to create an icon for the given picture (cropped or resized according to the “Resize pasted images” option). Similar actions can be performed using the Copy and Paste commands. ◊ Double-click icons or type Return or Enter to change the icon name and see the available icon images for the selected icon. ◊ Use the tab and arrow keys to navigate the icon list, or type an icon’s name to select it. ◊ Hold down the shift key to select multiple contiguous icons or the command key to make noncontiguous selections. Moving the mouse outside of the window while making a selection automatically scrolls the icon list. ◊ Most Icon Archiver menus are pretty straightforward, here’s a quick explanation of the less obvious ones: - View by File Order sorts the icons according to their original adding sequence, i.e. based on their physical position inside the icon archive; - Export Selected creates one or more custom icon files on your disk (same as dragging icons to the Finder); - Remove Duplicates removes all icons whose image is exactly the same, without checking their names; if you find two icons that look alike after a removal, they either have different family members (for example, one may include a 4-bit image that the other doesn’t have) or slightly different colors. Removing duplicates also sorts the icons by icon (i.e. by their image). - Filter Icons lets you remove specific classes of icons, based on their size (large or small) and color depth (black and white, 4 bits, or 8 bits). The AND and OR buttons in the Filter dialog, along with the must have, must not have and don’t care buttons, let you specify which icons to keep. All the icons that don’t match your request are removed. To remove all small icons and b&w icons, for example, you should check “must have” for “large 8-bit” and “large 4-bit”; check “don’t care” for all other icons; and check the OR button. This will read as follows: “Keep all the icons that have a large 8-bit image OR have a large 4-bit image, and remove all the others”. - Scan Folder Contents tells the Archiver to look for icons in all the files and subfolders that are inside a folder or disk, when you drop one in a window or on the Archiver’s icon. If this option is unchecked, only the custom icon for the folder or disk is searched. - Skip Nested Icon Archives tells the Archiver not to add the contents of its own archives to the front window, when one of them is found inside a folder or disk that’s being scanned. If this option is not checked, all nested archives that are small enough to fit in memory are added to the target window. Double-clicking an archive or dropping it on the Archiver’s icon in the Finder always opens a new window, whereas dragging an archive to an existing window merges its contents into the target window. - Skip Black & White Icons tells the Archiver to skip all icons that don’t have a color image. - Skip Small Icons tells the Archiver to skip all icons that don’t have a large image. - Add Icons to Front Window tells the Archiver not to open a new window when you add more icons by dropping items on the Archiver’s icon in the Finder or by using the “Open” menu command. This option doesn’t change anything if you add icons by dragging Finder items directly to an Icon Archiver window. - Use Resource ID in Names appends resource ID’s to icon names instead of a plain index. This only works when the icon doesn’t have its own name, so that the file name is used instead and an index or resource ID is appended to it. - Ignore Resource Names tells the Archiver to ignore all resource names and always use the file or folder name instead. This is useful when all the icon resources in a given collection have the same name, typically something as meaningless as “Custom”. - Resize Pasted Images sets the “Paste” behavior to “Resize” instead of “Split”. This means that pasting a large PICT into an Archiver window generates a scaled-down icon showing a resized version of the full original image. The default “Split” behavior generates a bunch of icons with solid background and no size change. - Choose Application lets you pick the default handler application for graphics files that are exported through the currently selected plugin. - Transparent Background makes the icon’s background transparent in the graphics formats that support this feature, so that the empty pixels around the icon are not painted in white. - Interlaced Graphics File writes the graphics file in interlaced format, so that a rough approximation of the image appears more quickly when sent through the Web and becomes more detailed as the rest of the file is transmitted. - Plugin Settings lets you modify the settings of the currently selected plugin, if it does have any. - Plugin Info displays some info about the current plugin and tells you which kind of code is running (68K or PPC). - Custom Icons is the recommended built-in output file format; custom icons are directly visible in the Finder. - Custom Folders is the alternate and less efficient built-in output file format, which creates folders rather than files. - [various plugins] make the Archiver generate the related graphics files when dragging icons to the Finder or exporting the currently selected icons. • Plugins ◊ Versions 2.0 and later can use external plugins to export the icons in many useful graphics formats. The plugins are specifically written for the Icon Archiver and must be stored in a folder named “Archiver Plugins”, which must be in the same folder as the Icon Archiver application itself. You can disable any unused plugins to save some memory by moving them out of the Archiver Plugins folder, or even disable them all by renaming the folder itself. Installing large plugins such as PNG File reduces the memory that’s available for icon archives, so you may have to increase the Archiver’s memory partition to open archives that would previously fit in the default 2048K partition. ◊ The Clip2gif Link plugin is a special PowerPC-only plugin that uses Yves Piguet’s clip2gif freeware utility to export the icon files. To use this plugin you must download clip2gif separately, then put the clip2gif application (or an alias to it) inside the Archiver Plugins folder. The application (or its alias) has to be named “clip2gif”, or the Clip2gif Link won’t be able to find it. This lets you generate GIF, JPEG and TIFF files right from the Icon Archiver; unfortunately, it only works on PowerPC machines and requires a specific version of clip2gif (earlier or later versions can’t be used). The clip2gif utility is available on info-mac and most other online services, and Yves Piguet’s email address is . ◊ The reason why there’s no GIF plugin in the distribution package is simple: UNISYS holds a license on the GIF format, and their requirements for shareware programs are way too expensive and restrictive for me. The PNG graphics format is much better than GIF, and it’s free. Many web browsers already support it, but unfortunately the Mac ones are not among them yet; you can send an email to Netscape or Microsoft and ask for PNG support to make them aware of the issue. (Last minute note: QuickTime 2.5 supports the GIF format, so the next version of the Archiver may take advantage of it). ◊ If you need the APIs and tech info to write your own Archiver plugins, send me an email. • Finder images ◊ The Icon Archiver lets you easily build large images directly in Finder windows, just like the ones found on many CD-ROMs. This is not necessarily a wise thing to do since opening these windows becomes much slower, but many people like the idea so here are some step-by-step instructions to make it work: - turn off the “resize pasted images” option; - copy a picture and paste it in an Archiver window, or drag a picture or a picture clipping to an Archiver window; - the picture is automatically split into icons as a series of 32x32 tiles with solid backgrounds; - drag all these icons to a Finder window; this is much easier if you do it one by one and put each icon near its the final location as you drag it; - carefully move the icons in the window so that they are close to each other, as in the original image - name the icons so that the top left icon is alphabetically first, and the bottom right one last; the last line of icons (or even all of the icons) should only have spaces and tabs in the names, so that they are not visible. ◊ When naming the icons, you can use spaces and tabs to make the names invisible. Since the tab character can’t be typed in directly, you’ll have to type it in SimpleText or in some other text processor, copy it, and later paste it in the Finder when the icon name is being edited. You can create as many invisible names as you need by using different sequences of spaces and tabs, as in: "tab-tab-tab-tab", "tab-tab-tab-space", "tab-tab-space-tab", "tab-tab-space-space", "tab-space-tab-tab", and so forth… This binary-like sequence allows you to have a precise alphabetical ordering for any number of icons, given that the tab character comes before the space when you sort by name. You should add more characters (starting with eight or ten tabs, for example) if you need more invisible names. • Filtering icons ◊ The “Filter icons” interface looks complicated, but there’s an easy way to understand it. Just read the settings loud as follows: The icons I want to keep… 1) must have… \ 2) must not have… | …a large black & white icon 3) don’t care about… / …AND (OR) they… 1) must have… \ 2) must not have… | …a large 4-bit color icon 3) don’t care about… / …AND (OR) they… … … … • Custom icons and folders ◊ The Icon Archiver can create either custom icons or custom folders when exporting icons or dragging them to the Finder. Many people distribute custom icons as empty folders because they are easier to create in the Finder, but sticking a custom icon on an empty folder creates two entries on your disk’s catalog: one for the folder and one for the invisible “Icon” file that actually contains the custom icon resources. Worse yet, the Finder doesn’t calculate the disk space used by custom folders and doesn’t delete the invisible file when you remove the custom icon from a folder (it empties the file and leaves it there). ◊ If you choose to create files instead of folders, you’ll keep your disk catalog smaller (faster searches and scans, easier disk fixes) and you’ll get the actual disk space used when you choose “Get Info” in the Finder. ◊ Custom icon files are not icon archives; when you double-click on a custom icon file, either its icon is added to the current archive in the Archiver or a new one is created. This is the same behavior you get when dragging a file on an Archiver window or dropping it on the Archiver’s icon in the Finder. • File size notes ◊ One user wrote: “My 2,300+ icon collection was 1.5 meg on individual folders. I created an Icon Archiver archive but that turned out to be 3.1 meg. Hmmm… Am I doing something wrong? Perhaps the Finder doesn’t give me an accurate folder size when I Get Info on my original icon collection?” ◊ Answer: the size of custom icons doesn’t show up in the Finder if they are sticked onto a folder, because the file that actually contains the icon resources is invisible. The Finder doesn’t add the size of invisible files when it looks up the total size of a disk or folder. In the case above there must be both custom icon files and custom icon folders in the collection, and 1.5 meg is the size of the custom icon files alone. To figure out the real size of a collection, you can create an Archiver archive with all of its icons and then export them back to your disk. Since the Archiver creates custom icon files, the Finder’s Get Info window will then display the real size of the original collection. • Skipped files ◊ As a general rule, skipping both B&W icons and small icons may make your scans slightly faster because more files will be skipped without even checking their contents. This is all you need to know if you are not a technically-oriented user; the rest of this paragraph contains a more detailed explanation for programmers and hackers. ◊ To make the folder and disk scanning faster, the Icon Archiver skips all files that couldn’t possibly contain any icon of the allowed types. Specifically, it checks the size of the resource fork and makes sure it’s at least as large as a resource fork containing only the resource map for one unnamed resource (310 bytes) plus the data of one icon resource. The minimum size of the icon resource depends on the current scanning options as follows: - 64 bytes = size of ics# (don’t skip B&W, don’t skip small) - 128 bytes = size of ics4 (skip B&W, don’t skip small) - 256 bytes = size of ICN# (don’t skip B&W, skip small) - 512 bytes = size of icl4 (skip B&W, skip small) ◊ If you use an automatic disk compression utility such as the StuffIt SpaceSaver, checking the resource fork size also prevents the Icon Archiver from decompressing many text files since they typically have some small resources describing their font and window settings. ◊ Note: this smart feature was suggested by Mark Nagata. • Troubleshooting ◊ If an Icon Archiver archive gets corrupted so that you can no longer open it, hold down the Option key when choosing Open from the File menu to enable archive recovery. Be aware that reading corrupted archives may cause system crashes, so close all applications and save all your data before using this feature. ◊ If the Icon Archiver crashes when you launch it, hold down the Option or Control key and launch it again. This lets you disable some of the advanced Archiver features that may be conflicting with your System configuration. • Icon Dearchiver ◊ The Icon Dearchiver is a small drag&drop utility that converts an Icon Archiver archive into one or more folders full of custom icons. You can easily do the same thing with the Icon Archiver, but the Dearchiver requires no registration and can be freely distributed along with your icon collections. For example, you don’t need my permission to include the Dearchiver with an icon archive that you wish to distribute over the Net (you don’t even have to be a registered user to distribute the Dearchiver, so go ahead and do it!). The Dearchiver is only 50K, or less than 30K if you compress it, which means it won’t blow up the size of your distribution files. • Icon Rescue ◊ Icon Rescue is a freeware utility that extracts all icons from Icon 7 and Zonkers! collections. It is available on my web and ftp sites. • Distribution ◊ This software is ©1996-97 Alessandro Levi Montalcini. It can be freely distributed as long as it is not modified and there’s no charge for it, but it may not be included in any commercial package without my consent. ◊ Personal registration codes should never be sold, distributed or made public. Any registration code found over the Internet or on any kind of publicly available media will cancel the registration that was associated to it. ◊ All online services and bulletin boards may make it available to their users at no charge other than the normal connection fees. ◊ All non-profit user groups may distribute it at no charge. ◊ All magazines may publish it on floppy disk or CD-ROM without asking me first, as long as I get a copy of the issue containing my software. ◊ All CD-ROM shareware collections and CD-ROM magazines may include it without my prior consent, as long as I get either a copy of the CD-ROM or an offer to buy the CD-ROM at a discounted price. ◊ All redistribution companies such as Pacific HiTech, AMUG, Celestin or Educorp may distribute it, as long as I get a copy of each media containing my software and a catalog of the company’s offerings (where applicable). ◊ The latest versions of my stuff are on http://persoweb.francenet.fr/~alm or ftp://ftp.alpcom.it/software/mac/LMontalcini. The ALM Share and ALM Free packages, which contain most of my stuff and can be registered at a very low price, are also available there. • Version history ◊ 2.2 - The Archiver can now export custom icons as folders. ◊ 2.1 - Switched to Kagi for shareware registrations. Added a new export plugin to create Kid Pix stamps and an option to ignore resource names. Archive corruption should no longer occur when other applications crash, and more archive recovery capabilities were added. The Display Manager is now supported, so that all windows are automatically moved onscreen when you change your monitor’s resolution on the fly. Fixed a couple of minor things in my application framework, and recompiled with the latest version of the CodeWarrior. ◊ 2.0 - The Archiver now supports external plugins that let you export your icons in many useful graphics formats including PICT, PNG, cicn, GIF, JPEG and TIFF (see the documentation for more details). Keyboard navigation of the icon lists is now implemented, so you can use the arrow keys or type an icon’s name to select it. Added basic archive recovery capabilities to resurrect some corrupted archives, typically those broken by a system crash that prevented the disk cache from being properly flushed to disk; hold down the Option key when choosing Open from the File menu to enable archive recovery. Added compatibility modes for System versions that cause the Archiver to crash; hold down the Option or Control key when launching the Archiver to manually disable some of its features. ◊ 1.0.2 - The new Icon Dearchiver utility is now included in the package. Pasting or dragging pictures into an Archiver window can now split the image in multiple solid-background icons, which can then easily be dragged to the Finder to build cool multi-icon images directly inside the Finder windows. ◊ 1.0.1 - Double-clicking an open archive now selects the appropriate window instead of displaying an error code; now reads 'ICN#' names even if “skip b&w icons” is checked; opens an empty archive window when launched alone; more careful checks should avoid launching crashes when the Drag Manager is installed on pre-7.1 systems; fixed a bug that could cause the “Don’t Save” button to be automatically pressed. ◊ 1.0 - First public release after months of beta testing. • Thanks to… ◊ Valentina Pavia, for putting up with my late night programming sessions; ◊ Kee Nethery and the Kagi staff, for their help and support; ◊ Gary Gonzalez and Charles Haspel of Binary Software, for their time and suggestions; ◊ Alberto Ricci, Fabrizio Oddone, Masatsugu Nagata, Jim Walker, Leonard Rosenthol, Peter Lewis, Jon Gotow, Jeremy Roussak, Rocco Moliterno, Dario Accornero, Marco Piovanelli, Amedeo Farello, Marc Moini, Paul Celestin, Maximilien Roi, Richard Foley, David-Artur Daix, and all the other programmers and testers that make it nicer and easier to work on the Mac; ◊ Giovanni Rava, Filippo Bellotti, Claudio Bovero, Luciano Baesso, Luca Martina, Mario Pettenghi, Michele Pizzi, Silvio Mercadante, and all the other Mac users and dealers who helped me somehow; ◊ Lilo Amar and the FranceNet staff, for giving you my web site; ◊ Claudio Racca, Luca Broglio, Roberto Borri and the CSP staff, for giving you my ftp site; • Disclaimer ◊ This software should never cause any damage, but you’re using it at your own risk. As an independent software developer, I can make no warranties whatsoever on it. • Have fun! ◊ And don’t forget to register your shareware, so that more cool inexpensive utilities can see the light in the future.